/*
 * @Author: 0x9DEFA478
 * @Date: 2024-08-02 20:00:39
 * @LastEditTime: 2024-08-12 20:26:19
 * @LastEditors: 0x9DEFA478
 * @Description: 
 * QQ:2652450237
 * ============================================================================================================================================
 * 
 * 
 * 
 *                                                                                               ************      ****************************
 *                                                                                             ************      ****************************  
 *                                                                                           ************      ****************************    
 *                                                                                         ************      ****************************      
 *                                                                                       ************      ************                        
 *                                                                                     ************      ************                          
 *                                                                                   ************      ************                            
 *                                                                                 ************      ************                              
 *                                                                               ************      ************                                
 *                                                                             ************      ************                                  
 *                                                                           ************      ************                                    
 *                                                                         ************      ************                                      
 *                                                                       ************      ************                                        
 *                                                                     ************      ************                                          
 *                                                                   ************      ************                                            
 *                                                                 ************      ************                                              
 *                                                               ************      ************                                                
 *                                                             ************      ************                                                  
 *                                                           ************      ************                                                    
 *                                                         ************      ************                                                      
 *                                                       ************      ************                                                        
 *                                                     ************      ************                                                          
 *                                                   ************      ************                                                            
 *                                                 ************      ************                                                              
 *                                               ************      ************                                                                
 *                                             ************      ************                                                                  
 *                                           ************      ************                                                                    
 *                                         ************      ************                                                                      
 *                                       ************      ************                                                                        
 *                                     ************      ************                                                                          
 *                                   ************      ************                                                                            
 *                                 ************      ************                                                                              
 *                               ************      ************                                                                                
 *                             ************      ************                                                                                  
 *                           ************      ************                                                                                    
 *                         ************      ************                                                                                      
 *       ****************************      ************                                                                                        
 *     ****************************      ************                                                                                          
 *   ****************************      ************                                                                                            
 * ****************************      ************                                                                                              
 * 
 * 
 * 
 * ============================================================================================================================================
 * 
 */
#ifndef hAPI_H_TS_Semaphore_H_
#define hAPI_H_TS_Semaphore_H_
#include "./H_TS_Event.h"
#include "./H_TS_Lock.h"




typedef struct{
  H_TS_Event ReleaseEvent;
  H_TS_Lock ReleaseLock;
  H_TS_Event AcquireEvent;
  H_TS_Lock AcquireLock;

  volatile Husize Value;
  Hsize MaxValue;
}H_TS_Semaphore;




/**
 * @brief 构造一个信号量
 * @param Semaphore 待构造的内存
 * @param MaxValue 信号量最大计数 最小为1
 * @param InitialValue 信号量初始计数
 * @return 无
 */
void H_TS_Semaphore_Init(H_TS_Semaphore* Semaphore,Husize MaxValue,Husize InitialValue);

/**
 * @brief 析构一个信号量
 * @param Semaphore 待析构的信号量
 * @return 目前实现只会返回0
 */
int H_TS_Semaphore_Deinit(H_TS_Semaphore* Semaphore);

/**
 * @brief 新建信号量
 * @param MaxValue 信号量最大计数 最小为1
 * @param InitialValue 信号量初始计数
 * @return 信号量对象 如果为NULL 则失败
 */
H_TS_Semaphore* new_H_TS_Semaphore(Husize MaxValue,Husize InitialValue);

/**
 * @brief 删除信号量
 * @param Semaphore 待删除的信号量
 * @return 0:成功 -1:信号量正在被其他线程占用
 */
int delete_H_TS_Semaphore(H_TS_Semaphore* Semaphore);

/**
 * @brief 向信号量释放信号 由中断调用
 * @param Semaphore 待释放信号的信号量
 * @return 释放信号之前信号量的值 如果为最大值的话说明释放失败(信号已达最大值)
 */
Husize H_TS_Semaphore_TryRelease_ISR(H_TS_Semaphore* Semaphore);

/**
 * @brief 向信号量释放信号
 * @param Semaphore 待释放信号的信号量
 * @return 释放信号之前信号量的值 如果为最大值的话说明释放失败(信号已达最大值)
 */
Husize H_TS_Semaphore_TryRelease(H_TS_Semaphore* Semaphore);

/**
 * @brief 向信号量释放信号
 * @param Semaphore 待释放信号的信号量
 * @return 释放信号之前信号量的值
 */
Husize H_TS_Semaphore_Release(H_TS_Semaphore* Semaphore);

/**
 * @brief 向信号量释放信号
 * @param Semaphore 待释放信号的信号量
 * @param Timeout 以Tick为单位的超时时间
 * @return 释放信号之前信号量的值 如果为最大值的话说明超时
 */
Husize H_TS_Semaphore_Release_Time(H_TS_Semaphore* Semaphore,H_TS_Tick Timeout);

/**
 * @brief 尝试获取信号量的信号
 * @param Semaphore 待获取信号的信号量
 * @return 获取到信号前的信号量的值 如果为0代表获取失败
 */
Husize H_TS_Semaphore_TryAcquire(H_TS_Semaphore* Semaphore);

/**
 * @brief 获取信号量的信号
 * @param Semaphore 待获取信号的信号量
 * @return 获取到信号前的信号量的值 如果为0代表获取失败
 */
Husize H_TS_Semaphore_Acquire(H_TS_Semaphore* Semaphore);

/**
 * @brief 获取信号量的信号
 * @param Semaphore 待获取信号的信号量
 * @param Timeout 以Tick为单位的超时时间
 * @return 获取到信号前的信号量的值 如果为0代表获取失败
 */
Husize H_TS_Semaphore_Acquire_Time(H_TS_Semaphore* Semaphore,H_TS_Tick Timeout);

/**
 * @brief 锁定内部的Release锁
 *        Release锁是Semaphore在Release时用于数据保护的互斥锁
 *        使得外界可以在一定条件下复用这个锁
 *        锁定该锁时可能使得线程对该锁的Release操作被阻塞
 * @param Semaphore 信号量
 * @return 无
 */
void H_TS_Semaphore_ReleaseLock(H_TS_Semaphore* Semaphore);

/**
 * @brief 解锁内部的Release锁
 *        Release锁是Semaphore在Release时用于数据保护的互斥锁
 *        使得外界可以在一定条件下复用这个锁
 * @param Semaphore 信号量
 * @return 无
 */
void H_TS_Semaphore_ReleaseUnlock(H_TS_Semaphore* Semaphore);

/**
 * @brief 锁定内部的Acquire锁
 *        Acquire锁是Semaphore在Acquire时用于数据保护的互斥锁
 *        使得外界可以在一定条件下复用这个锁
 *        锁定该锁时可能使得线程对该锁的Acquire操作被阻塞
 * @param Semaphore 信号量
 * @return 无
 */
void H_TS_Semaphore_AcquireLock(H_TS_Semaphore* Semaphore);

/**
 * @brief 解锁内部的Acquire锁
 *        Acquire锁是Semaphore在Acquire时用于数据保护的互斥锁
 *        使得外界可以在一定条件下复用这个锁
 * @param Semaphore 信号量
 * @return 无
 */
void H_TS_Semaphore_AcquireUnlock(H_TS_Semaphore* Semaphore);




#endif //hAPI_H_TS_Semaphore_H_
